LegendBox Tutorial Basic

Styling

Before proceeding, see the Box tutorial for basic styling options.

Fonts:
A legend entry's font can be defined by specifying a default font for all entries.

[C#]
Chart.LegendBox.DefaultEntry.LabelStyle.Font = new Font("Verdana",8);

[Visual Basic]
Chart.LegendBox.DefaultEntry.LabelStyle.Font = New Font("Verdana",8)

See also: Using Colors

Template

The default columns of a legend are Name, Value, and Icon. They are represented in the Template property as tokens. The Template property allows reordering,exclusion of any particular column, or additional tokens that represent the same as the legend entries such as "%ElementCount".

Example: The following code reorders legend columns.

[C#]
Chart.LegendBox.Template = "%Icon%Value%Name";

[Visual Basic]
Chart.LegendBox.Template = "%Icon%Value%Name"

Example: The following code excludes the icon column.

[C#]

Chart.LegendBox.Template = "%Value%Name";
[Visual Basic]
Chart.LegendBox.Template = "%Value%Name"

Example: The following code inserts additional columns.

[C#]

Chart.LegendBox.Template = "%Value%Name%Icon%ElementCount%Average";
[Visual Basic]
Chart.LegendBox.Template = "%Value%Name%Icon%ElementCount%Average"

Text Alignment

The columns can be either icons or text. When text is used, it can be aligned either to the right or left. These alignment settings can be specified by using an array of StringAlignment enumerations that correspond to the above template tokens (IconValueName) respectively.

Example: The following code specifies the alignment of three columns in a legend box.

[C#]

Chart.LegendBox.ColumnAlignments = new StringAlignment[]{StringAlignment.Far, StringAlignment.Center, StringAlignment.Far};
[Visual Basic]
Chart.LegendBox.ColumnAlignments = New StringAlignment(){StringAlignment.Far, StringAlignment.Center, StringAlignment.Far}

Positioning

Orientation
To position a legend box, the LegendBox.Position or LegendBox.Orientation properties must be defined.

[C#]

LegendBox.Orientation = Orientation.BottomLeft;
[Visual Basic]
LegendBox.Orientation = Orientation.BottomLeft

The position property is an object type and accepts a legacy LegendBoxPosition enumeration or a Point object, which specifies the absolute position in pixels.

Tip:Using LegendBoxPosition is not recommended because Orientation has more options.

[C#]

LegendBox.Position = LegendBoxPosition.Bottom;

[Visual Basic]

LegendBox.Position = LegendBoxPosition.Bottom

Illustration of legend box positions and corresponding properties.

Absolute Position
Using a Point object will specify an absolute position. Other elements on a chart will not be affected by the position and the legend will overlap objects beneath it.

[C#]

LegendBox.Position = new Point(200,20);

[Visual Basic]

LegendBox.Position = New Point(200,20)

Absolute Position with Size

The legendbox absolute position can also be specified with a size in addition to the point. This is accomplished by using a Rectangle object.

[C#]

LegendBox.Position = new Rectangle(new Point(200,20),new Size(100,100));

[Visual Basic]

LegendBox.Position = New Rectangle(New Point(200, 20), New Size(100, 100))

Tip: When using an absolute position, it is useful to set a transparency for the box'es background color so underlying objects can still be seen if necessary.

Specifying a LegendBox size

The legendbox.Position property can also take a Size object by itself. In this case, the position of the legendbox is not affected but the size specified is a static size and will not change. It will force the legend entries in the legendbox to display in the best possible way provided there is enough room for them.

[C#]

LegendBox.Position = new Size(100,100);

[Visual Basic]

LegendBox.Position = New Size(100, 100)

In Title box
Another useful option is to completely eliminate the legend box and move the entries into the title box. To accomplish this, a title box position FullWithLegend is used.

[C#]
Chart.TitleBox.Position = TitleBoxPosition.FullWithLegend;

[Visual Basic]
Chart.TitleBox.Position = TitleBoxPosition.FullWithLegend

Note: The entries in a title box are positioned opposite to the alignment of the title (TitleBox.Label.Alignment). If the title is right-aligned the entries will position themselves on the left side of the title box.

Invisible Legend
To completely eliminate the legend from a chart set the Visibility of the legend to false.

[C#]
Chart.LegendBox.Visible = false;

[Visual Basic]
Chart.LegendBox.Visible = False

Legend Entries

Manipulating the content
Entries in the legend are for most cases generated to represent each series. However, if a Series.Palette or PaletteName is specified, each element in that series will automatically insert its entry into the legend. Legend entries specific to each series and element can be accessed through their parent object. For example, an element's legend entry is accessed through:

myElement.LegendEntry.__ = __

AxisMarker objects used with axes or elements are also automatically inserted into the legend and their entries are accessed through:

myAxisMarker.LegendEntry.__ = __

To prevent an axis marker from entering into the legend, the entry's visibility can be turned off:

[C#]

myAxisMarker.LegendEntry.Visible = false;
[Visual Basic]
myAxisMarker.LegendEntry.Visible = False

To exclude the all series entries from a legend box the following code can be used:

[C#]

Chart.DefaultSeries.LegendEntry.Visible = false;

[Visual Basic]
Chart.DefaultSeries.LegendEntry.Visible = False

Custom Entries
Custom entries can be added to the legend by instantiating and adding them to the ExtraEntries property of a LegendBox.

[C#]

LegendEntry myEntry = new LegendEntry();
myEntry.Name = "CustomName";
myEntry.Value = "CustomValue;
Chart.LegendBox.ExtraEntries.Add(myEntry);

[Visual Basic]

Dim myEntry As New LegendEntry()
myEntry.Name = "CustomName"
myEntry.Value = "CustomValue
Chart.LegendBox.ExtraEntries.Add(myEntry)

Header Entry
Each legend has a ready made header entry. These are used to describe the columns of your legend. The header entry is activated by setting the Visible property.

[C#]

LegendBox.HeaderEntry.Visible = true;

[Visual Basic]

LegendBox.HeaderEntry.Visible = true

Header text can be modified with the traditional text properties.
LegendBox.HeaderEntry.Name = "Series Name";

To change the icon text a custom attribute must be used

[C#]

LegendBox.HeaderEntry.CustomAttributes = "Icon=Icon Header";

[Visual Basic]

LegendBox.HeaderEntry.CustomAttributes.Add("Icon","Icon Header")

Attributes will be covered further in the advanced tutorial.

More Tips:
Using your own entries.
• In some cases, it is required to use your own custom entries instead of the default ones. The best way to accomplish this is to set Chart.DefaultSeries.LegendEntry.Visible = false; and add your entries as shown above.
• Moving entries to the title box may save valuable space when there are few series and chart sizes are small.

The features covered in this tutorial are the most common but only scratch the capability surface of LegendBox objects.

For more advanced features go on to the advanced tutorial.